@backand/vanilla-sdk

vanilla-sdk

Backand SDK for JavaScript. This SDK enables you to communicate comfortably and quickly with your Backand app. It requires zero configurations, no installations and no requirements.

Overview

Backand's Vanilla SDK is designed for easy integration with plain JavaScript applications, as well as other applications that do not make use of any particular JavaScript framework. If you are working with Angular 1, Angular 2, or Redux, we provide the following wrapper SDKs:

Platform	SDK link
Angular 1	https://github.com/backand/angular1-sdk
Angular 2	https://github.com/backand/angular2-sdk
Redux	https://github.com/backand/redux-sdk

If you are not working with the above platforms, you can simply use this SDK directly with any web application - simply include the SDK in your client-side code, then get started!

Installation

To install the Vanilla SDK, use the correct command for your dependency management platform:

Provider	Command
npm	$ npm i -S @backand/vanilla-sdk
yarn	$ yarn add @backand/vanilla-sdk
bower	$ bower install backand-vanilla-sdk
clone/download via Git	$ git clone https://github.com/backand/vanilla-sdk.git

Import

Next, import the SDK into your project. To import in a bundler-based system, use the following JavaScript:

import backand from '@backand/vanilla-sdk'
const backand = require('@backand/vanilla-sdk')

Otherwise, include the following tags in your index.html file:

<script src="node_modules/@backand/vanilla-sdk/dist/backand.min.js"></script>
<script src="backand.min.js"></script>

Browser Support

Latest ✔	Latest ✔	Latest ✔	Latest ✔	Latest ✔	10+ ✔

Quick Start

Getting started with the SDK is as simple as configuring access to a Back& application, then calling getList on a relevant object:

backand.init({
  appName: 'APP_NAME',
  anonymousToken: 'ANONYMOUS_TOKEN'
});

backand.object.getList('users')
  .then((response) => {
      console.log(response);
  })
  .catch(function(error){
      console.log(error);
  });

This connects your Back& application (with the app name of APP_NAME and an anonymous access token of ANONYMOUS TOKEN) to your current project. Once the connection is configured, the SDK uses this connection information to construct HTTP requests to your API. Result data is returned in the response object as the member variable data. In the case of getList, this will be a JSON array of objects pulled from the users table in your Back& application. You can easily change the table being manipulated by replacing users with the name of any object in your system.

API Reference

backand.init():

The init() method creates a new Back& SDK instance with the supplied configuration.

Sample Code

var config = {
   appName: 'APP_NAME',
   anonymousToken: 'ANONYMOUS_TOKEN'
             };
backand.init(config);

The available parameters for the config parameter are:

Param Name	Data Type	Usage	Required?	Default Value
appName	string	Sets the name of your backand app	required
anonymousToken	string	Sets the anonymous token of your backand app	required
useAnonymousTokenByDefault	boolean	Determines whether the sdk should use the anonymousToken when there is no other token	optional	true
signUpToken	string	Sets the signup token of your backand app	optional
apiUrl	string	Sets the API url of backand servers	optional	https://api.backand.com
storage	object	Sets the storage type to use (local/session/implementation of StorageAbstract)	optional	localStorage
storagePrefix	string	Sets prefix to use in the storage structure	optional	BACKAND_
manageRefreshToken	boolean	Determines whether the sdk should manage refresh tokens internally	optional	true
runSigninAfterSignup	boolean	Determines whether the sdk should run signin after signup automatically	optional	true
runSocket	boolean	Determines whether the sdk should run socket automatically	optional	false
socketUrl	string	Sets the socket url of backand servers	optional	https://socket.backand.com
isMobile	boolean	Determines whether the sdk is part of a mobile application	optional	false
mobilePlatform	string	sets the platform used to build the mobile application ('ionic'/'react-native')	optional	'ionic'
runOffline	boolean	Determines whether the sdk should run pending offline actions. (cached data and queued requests)	optional	false
allowUpdatesinOfflineMode	boolean	Determines whether the sdk will allow object updates or deletion while in offline mode. When set to "true", all objects must contain a field, "updatedAt", that needs to be before the SDK entered offline mode. Any update/delete operations on fields with an "updatedAt" that occurs after the SDK entered offline mode will fail.	optional	false
beforeExecuteOfflineItem	function	Sets the function to be called before each cached request. In order to determines whether to dispatch the next request or drop it, you must call return with a valid boolean.	optional	(request) => { return true }
afterExecuteOfflineItem	function	Sets the function to be called after each cached request.	optional	(response, request) => { }

SDK Properties:

Below is a list of the properties offered by the SDK, a description of the functionality handled by that property, and the list of methods provided by that property:

Name	Methods	Description
constants	EVENTS, URLS, SOCIALS	Provides access to constants in the SDK
helpers	filter, sort, exclude, StorageAbstract	Provides helper methods for working with the SDK
direct properties	useAnonymousAuth, useBasicAuth, signin, signup, socialSignin, socialSigninWithToken, socialSignup, requestResetPassword, resetPassword, changePassword, signout, getSocialProviders	These are properties available directly on the Backand SDK object, mostly focused on Authentication
defaults	none	This stores the current app's configuration in the SDK
object	getList, create, getOne, update, remove, get (action), post (action)	This encapsulates all methods used to manipulate objects
file	upload, remove	Provides helper methods for working with files
query	get, post	Allows you to work with custom query objects
user	getUserDetails, getUsername, getUserRole, getToken, getRefreshToken	Provides information on the current authenticated user
on	none	This is the event handler for socket.io functions, replacing socket.on
offline	cache, queue, setOfflineMode	provides management for offline execution capabilities

Default Events:

By default, the Back& SDK emits the following events that your code can respond to:

Name	Description	Syntax
SIGNIN	dispatched on signin	window.addEventListener(backand.constants.EVENTS.SIGNIN, (e)=>{}, false);
SIGNOUT	dispatched on signout	window.addEventListener(backand.constants.EVENTS.SIGNOUT, (e)=>{}, false);
SIGNUP	dispatched on signup	window.addEventListener(backand.constants.EVENTS.SIGNUP, (e)=>{}, false);
START_OFFLINE_MODE	dispatched on start offline mode	window.addEventListener(backand.constants.EVENTS.START_OFFLINE_MODE, (e)=>{}, false);
END_OFFLINE_MODE	dispatched on end offline mode	window.addEventListener(backand.constants.EVENTS.END_OFFLINE_MODE, (e)=>{}, false);

SDK Methods:

NOTE:

• All Methods return a Promise -> you can work with the response using .then() and .catch()
• You can see the response schema here

Authentication:

Authentication methods are called directly on the SDK, without any properties: backand.signin(username, password)

Signin

Signin with username and password in order to get access_token to be used in all other calls. If you don't have users you should use anonymous token only.

Parameters

name	type	description
username	string	the username to authenticate
password	string	the user's password

Sample Code

backand.signin(username, password)
  .then(res => {
    console.log('signin succeeded with user:' + res.data.username);
  })
  .catch(err => {
    console.log(err);
  });

Signup

Creates a new user in your app. in signup you must provide the basic details of username email, first name, last name and password

Parameters

name	type	description
firstName	string	the user's first name
lastName	string	the user's last name
email	string	the user's email
password	string	the user's password
confirmPassword	string	the value entered by the user when asked to confirm the password during registration
parameters	object	An object containing information for any paremeters to the signup call. This allows you to set additional info on the user object at registration time

Sample Code

backand.signup(firstName, lastName, email, password, confirmPassword, parameters = {})
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Change Password

Changes the password of the current user

Parameters

name	type	description
oldPassword	string	the user's old password
newPassword	string	the user's desired new password

Sample Code

backand.changePassword(oldPassword, newPassword)
  .then(res => {
    console.log('Password changed');
  })
  .catch(err => {
    console.log(err);
  });

Social Media Authentication:

socialSignin (also for Signup)

Signs the user into a Back& application using a social media provider as the authentication method. This opens a dialog window supplied by the social media network provider. If the user does not have an account with the selected provider, they will be prompted to create one as a part of this process.

Parameters

name	type	description
provider	string	Name of the provider to authenticate with. The full list can be obtained by calling backand.getSocialProviders(scb)

Sample Code

backand.socialSignin(provider)
  .then(res => {
    console.log('signin succeeded with user:' + res.data.username);
  })
  .catch(err => {
    console.log(err);
  });

CRUD:

The following methods perform create, retrieve, update, and delete functionality on a Back& object.

GetList

Fetches a list of records from the specified object. Uses options to store filter data

Parameters

name	type	description
object	string	Name of the Back& object to work with
options	object	A hash of filter options. Allowed options are: pageSize, pageNumber, filter, sort, search, exclude, deep, relatedObjects

Sample Code

backand.object.getList(object, options)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Sample Code with filter options

let options = {
  sort: backand.helpers.sort.create('creationDate', backand.helpers.sort.orders.desc),
  exclude: backand.helpers.exclude.options.all,
  filter: backand.helpers.filter.create('user', backand.helpers.filter.operators.relation.in, userId),
  pageSize: 20,
  pageNumber: 1
};
backand.object.getList(object, options)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

GetOne

Retrieves a single record from the specified object.

Parameters

name	type	description
object	string	Name of the Back& object to work with
id	integer	ID of the record to retrieve, subject to the filter specified in options
options	object	A hash of filter options. Allowed options are: deep, exclude, level

Sample Code

backand.object.getOne(object, id, options)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Create

Creates a record with the provided data in the specified object

Parameters

name	type	description
object	string	Name of the Back& object to work with
data	object	Data to use in the creation of the new record
options	object	A hash of filter options. Allowed options are: returnObject, deep
parameters	object	Parameters for the action to operate upon

Sample Code

backand.object.create(object, data, options, parameters)
  .then(res => {
    console.log('object created');
  })
  .catch(err => {
    console.log(err);
  });

Sample Code with filter options and parameters

let options = {
  returnObject: true
};
let parameters = {
  inputParameter1: 'value1',
  inputParameter2: 'value2'
};
backand.object.create(object, data, options, parameters)
  .then(res => {
    console.log('object created');
  })
  .catch(err => {
    console.log(err);
  });

Update

Updates a record with the specified ID in the specified object with the provided data.

Parameters

name	type	description
object	string	Name of the Back& object to work with
id	integer	ID of the object to update
data	object	Data to update the record with
options	object	A hash of filter options. Allowed options are: returnObject, deep
parameters	object	Parameters for the action to operate upon

Sample Code

backand.object.update(object, id, data, options, parameters)
  .then(res => {
    console.log('object updated');
  })
  .catch(err => {
    console.log(err);
  });

Remove

Deletes a record from the specified object with the specified ID

Parameters

name	type	description
object	string	Name of the Back& object to work with
id	integer	ID of the object to update
parameters	object	Parameters for the action to operate upon

Sample Code

backand.object.remove(object, id, parameters)
  .then(res => {
    console.log('object removed');
  })
  .catch(err => {
    console.log(err);
  });

Trigger object actions (GET)

Triggers custom actions that operate via HTTP GET requests

Parameters

name	type	description
object	string	Name of the Back& object to work with
action	string	Name of the action to trigger
parameters	object	Parameters for the action to operate upon

Sample Code

backand.object.action.get(object, action, parameters)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Trigger object actions (POST)

Triggers custom actions that operate via HTTP POST requests

Parameters

name	type	description
object	string	Name of the Back& object to work with
action	string	Name of the action to trigger
data	object	Object data to send as the body of the POST request
parameters	object	Parameters for the action to operate upon

Sample Code

backand.object.action.post(object, action, data, parameters)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Socket Communications

You can easily integrate with our Socket functionality using the on method. Socket signin and signout are handled automatically by the SDK.

On

Event handler for broadcast Socket events.

Parameters

name	type	description
eventName	string	Name of the socket event to subsccribe to
callback	function	Callback triggered when eventName is received

Sample Code

  //Wait for server updates on 'items' object
  Backand.on('items_updated', function (data) {
    //Get the 'items' object that have changed
    console.log(data);
  });

File

This property allows you to work with server-side actions, interacting with the related files directly. You can use this after you have finished creating a server-side action in the Back& dashboard, in the Actions tab of an object (object -> actions tab -> Backand Files icon -> name: 'files')

Upload

Uploads a file for a server-side action

Parameters

name	type	description
object	string	Name of the object controlling the desired server-side action
fileAction	string	The name of the file action to work with
filename	string	The name of the file to upload
filedata	string	The file's data

Sample Code

backand.file.upload(object, 'files', filename, filedata)
  .then(res => {
    console.log('file uploaded. url: ' + res.data.url);
  })
  .catch(err => {
    console.log(err);
  });

Remove

Removes a file from a server-side action file set.

Parameters

name	type	description
object	string	Name of the object controlling the desired server-side action
fileAction	string	The name of the file action to work with
filename	string	The name of the file to remove

Sample Code

backand.file.remove(object, 'files', filename)
  .then(res => {
    console.log('file deleted');
  })
  .catch(err => {
    console.log(err);
  });

User:

The user property returns data about the connected user (getUserDetails, getUsername, getUserRole, getToken, getRefreshToken).

GetUserDetails

Gets the connected user's details.

Parameters

name	type	description
force	boolean	Forces the SDK to refresh its data from the server. Default: FALSE

Sample Code

backand.user.getUserDetails(force)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Query:

The query property lets you initiate a custom Back& query using either HTTP GET or HTTP POST.

get

Calls a custom query using a HTTP GET
NOTE: this method will be deprecated soon. please use backand.query.post instead

Parameters

name	type	description
name	string	The name of the query to work with
parameters	object	Parameters to be passed to the query

Sample Code

backand.query.get(name, parameters)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

post

Calls a custom query using a HTTP POST

Parameters

name	type	description
name	string	The name of the query to work with
parameters	object	Parameters to be passed to the query

Sample Code

backand.query.post(name, parameters)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Offline:

The offline property allows you to control the SDK's offline mode. When the SDK detects that it has lost internet connection, it will queue requests internally. Based on the configuration provided to the init() function, this can result in either a delay prior to call execution or an error response to any update or delete calls. Once internet connection is restored, the queued commands are sent to the server, and the responses should be handled asynchronously through standard promise resolution

setOfflineMode

This function is used to enable and disable offline mode for debugging purposes. When true, the SDK will operate in offline mode. When false, the SDK will communicate over the web.

Parameters

name	type	description
force	boolean	Sets the SDK to operate in - or exit from - offline mode.. Default: TRUE

Sample Code

// Enter offline mode
backand.offline.setOfflineMode(true);
// Exit offline mode
backand.offline.setOfflineMode(false);

cache

An object in which the cached data is stored

Sample Code

backand.offline.cache;

queue

All requests queued during offline mode are stored here. These operations will be dispatched when offline mode ends.

Sample Code

backand.offline.queue;

Examples and further reading

To view the demo web page, just run npm start - example page.

License

MIT